package flare.data.converters
{
  import flare.data.DataSchema;
  import flare.data.DataSet;

  import flash.utils.IDataInput;
  import flash.utils.IDataOutput;

  /**
   * Interface for data converters that map between an external data file
   * format and ActionScript objects (e.g., Arrays and Objects).
   */
  public interface IDataConverter
  {
    /**
     * Converts data from an external format into ActionScript objects.
     * @param input the loaded input data
     * @param schema a data schema describing the structure of the data.
     *  Schemas are optional in many but not all cases.
     * @return a DataSet instance containing converted data objects.
     */
    function read(input:IDataInput, schema:DataSchema = null):DataSet;

    /**
     * Converts data from ActionScript objects into an external format.
     * @param data the data set to write.
     * @param output an object to which to write the output. If this value
     *  is null, a new <code>ByteArray</code> will be created.
     * @return the converted data. If the <code>output</code> parameter is
     *  non-null, it is returned. Otherwise the return value will be a
     *  newly created <code>ByteArray</code>
     */
    function write(data:DataSet, output:IDataOutput = null):IDataOutput;
  } // end of interface IDataConverter
}